Wiki Notes

Appearance

04. Tools、MCP与外部系统接入 ​

版本：v1.3

最后更新：2026-07-09

导读：把 Tool、MCP 和 Skill 分开看 ​

如果你现在最想搞清楚的是三者的边界，建议先按下面顺序读：

  1. 04A-Tool能力接口与执行边界
  2. 04B-MCP协议与连接器接入
  3. 04C-Skill任务封装与复用

本页继续保留总览，负责把 tools / MCP / connectors / skills / handoff / server tools 放在同一张工程地图里；上面三页分别负责把：

  • Tool 讲成能力接口与执行边界
  • MCP 讲成协议层与接入边界
  • Skill 讲成任务封装与复用入口

0. 先用一张表把三者拆开 ​

很多团队的问题不是没听过这三个词，而是三者总在一张图里互相代指。更实用的拆法通常是：

对象一句话定义它最该解决什么典型 owner
Tool一个最小可执行能力接口参数、结果、副作用、审批、重试业务系统 / 平台能力 owner
MCP一层把能力标准化暴露出去的协议tools / resources / prompts 如何被发现、读取、调用接入层 / 基础设施 owner
Skill一个可复用任务能力包指令、上下文、允许工具、执行策略、输出契约应用团队 / 流程 owner

如果你现在最困惑的是：

  • “这个动作到底该怎么设计接口”，先看 Tool
  • “这些能力怎么标准化接出去”，先看 MCP
  • “某类任务怎么复用，不想只剩一段 prompt”，先看 Skill

0.1 用同一个事故分诊例子看，会更容易分清 ​

假设你要做“线上事故分诊”：

  • Tool 层会关心：read_recent_alerts、search_runbook、create_incident_ticket 这几个动作分别怎么定义。
  • MCP 层会关心：这些动作、runbook 文档和值班模板如何按 tools / resources / prompts 暴露给不同宿主。
  • Skill 层会关心：事故分诊这个任务启动时要注入什么上下文、允许哪些工具、什么时候必须升级、输出格式是什么。

换句话说：

  • Tool 关注“做什么”
  • MCP 关注“怎么接”
  • Skill 关注“怎么把这类任务稳定做完”

1. Agent 为什么离不开工具 ​

没有工具的 Agent，通常只能：

  • 说
  • 猜
  • 基于已有上下文组织答案

一旦你希望系统：

  • 搜索实时信息
  • 访问文件
  • 查数据库
  • 调业务 API
  • 自动执行操作

你就一定会进入工具层设计。

Agent 的很多上限，最终都不是由“模型有多聪明”决定，而是由“工具接得好不好”决定。

2. Tool Use 的本质 ​

工具调用的本质不是“模型执行代码”，而是：

  1. 模型输出一个结构化动作请求
  2. 应用或运行时真正去执行
  3. 执行结果回传给模型

这意味着：

  • 模型负责决策
  • 应用负责执行

这也是安全设计的基础。

3. 一个好工具应该长什么样 ​

一个好工具通常具备这 6 个特征：

  1. 名字清楚
  2. 描述清楚
  3. 参数少而准
  4. 输入输出稳定
  5. 错误可理解
  6. 副作用边界清楚

好例子 ​

  • search_web(query)
  • get_ticket(ticket_id)
  • list_project_files(path)

差例子 ​

  • do_anything(data)
  • process_request(input, mode, extra, flag)

差工具会让模型：

  • 不知道什么时候该用
  • 不知道参数怎么填
  • 出错后难以恢复

4. 工具设计的关键原则 ​

4.1 查询和写入分离 ​

不要把读和写塞进一个工具。

更好的方式：

  • get_customer_info(customer_id)
  • update_customer_info(customer_id, fields)

好处：

  • 权限更清楚
  • 审批更容易
  • 审计更容易

4.2 高风险工具最小化 ​

高风险工具包括：

  • 发邮件
  • 写数据库
  • 提交工单
  • 触发支付
  • 操作生产环境

这类工具建议：

  • 参数更严格
  • 默认不可直接调用
  • 必须审批

4.3 参数 schema 不要冗余 ​

参数越多：

  • 模型越容易填错
  • 评测越麻烦
  • 失败恢复越复杂

4.4 错误信息要可操作 ​

不要只返回：

  • error

更好的错误应该说明：

  • 为什么失败
  • 哪个参数不合法
  • 是否可重试

5. OpenAI 的工具能力应该怎么学 ​

根据 OpenAI 官方文档在 2026-07-01 可访问的内容，建议按下面顺序学：

  1. Tools Guide
  2. Function Calling
  3. 具体工具类型
  4. Agents SDK 中的工具与运行时

重点关注：

  • web search
  • code execution / sandbox 使用场景
  • tool search
  • connectors / MCP

其中一个很重要的现实点是：

  • web search 让模型访问最新信息
  • tool search 用于延迟加载大工具面

这两类能力对复杂 Agent 都很重要。

6. 先把工具类型分清楚，再谈怎么接 ​

很多人一开始学工具，会把所有外部能力都混在一起说成“函数调用”。这会导致后面在执行位置、权限归属和成本评估上全部混乱。

更实用的分类方式通常是四类：

类型谁来执行适合什么场景
内建工具平台或模型运行时web search、file search、computer use 这类平台能力
function calling你的应用你自己控制的业务 API、数据库查询、内部动作
remote MCP远端 MCP server已经标准化暴露的外部服务或工具集合
connectors平台维护的第三方接入层Dropbox、Google Workspace 等常见 SaaS

根据 OpenAI Using tools 与 MCP and Connectors 文档在 2026-07-07 可访问的说明，Responses API 里可以组合 built-in tools、function calling、tool search 与 remote MCP，而 connectors 与 remote MCP 都通过 mcp 这一类工具形态接入。

这个区分非常重要，因为它决定了几个关键问题：

  1. 工具真正在哪执行。
  2. 出问题时谁负责兜底。
  3. 审批和日志该落在哪一层。
  4. 机密信息到底暴露给了谁。

6.1 built-in tools、local shell、hosted shell 和 code interpreter 不是一回事 ​

OpenAI 当前官方工具文档已经把这几类能力拆得很明确：

  • built-in tools：平台直接提供的能力，例如 web search、file search、computer use。
  • shell：让模型通过终端环境执行命令，既可以是本地执行，也可以是 OpenAI 托管执行。
  • code interpreter：更偏受控 Python 沙箱，适合数据分析、计算、脚本化处理。

这几类能力不要混成一个概念，因为它们回答的是不同问题：

  • 你到底要的是“访问外部信息”
  • 还是“跑命令和脚本”
  • 还是“在受限 Python 环境里做计算”

更实用的判断通常是：

  • 要查实时网页、查文件、点界面：先看 built-in tools。
  • 要 build-test-run、跑系统命令、读写项目文件：先看 shell / local shell。
  • 要做表格分析、数值处理、快速 Python 计算：先看 code interpreter。

6.2 tool search 解决的是“大工具面加载成本”，不是权限问题 ​

OpenAI 当前 Using tools 和 Tool search 文档都已经明确说明：

  • tool_search 允许模型按需搜索并加载 deferred tool definitions
  • 只有 gpt-5.4 及以后模型支持

这件事的工程意义很大，因为很多 Agent 一接企业工具就会遇到：

  • 工具定义太多
  • 每轮都把全部 schema 塞进上下文
  • token 成本和延迟同时上升

tool search 更像是在解决：

  • 工具面过大时的上下文装配问题

但它并不替你自动解决：

  • 哪些工具该暴露
  • 哪些工具有权限
  • 哪些工具需要审批

所以正确心智通常是：

  • tool search 负责按需加载
  • allowed_tools / policy / approval 负责暴露边界

6.3 MCP、Skill、Tool 最好按“三层模型”理解 ​

很多团队一提 Agent 接入层，就会一句话把 MCP、skill、tool 全部堆在一起说成“我们接了很多能力”。这会让讨论很快失焦，因为你其实可能在混着说三件完全不同的事：

  • 具体能执行什么动作
  • 这些动作按什么协议暴露出来
  • 在什么场景下把这些动作组织成可复用工作单元

更稳的理解方式通常是下面这三层：

层级它回答的问题核心对象典型产物
Tool系统到底能执行什么动作单个能力接口name、description、schema、side effects
MCP这些能力如何被标准化暴露和连接client-server protocolserver、tools、resources、prompts、auth
Skill针对某类任务，怎么把能力组织成一个可复用单元orchestration packageinstructions、allowed tools、context、policy、eval checklist

根据 MCP 官方 architecture 在 2026-07-09 可访问的内容，MCP 规范里明确强调的是 tools、resources、prompts 等协议原语；它并没有把 skill 定义成协议级对象。也就是说：

  • tool 是最小执行单元
  • MCP 是把 tool/resource/prompt 暴露出去的协议层
  • skill 更像应用层或平台层的场景化封装

这件事必须说清，因为它直接影响你的系统分层：

  • tool 设计错了，模型不会稳定调用
  • MCP 边界画错了，跨系统授权和信任关系会混乱
  • skill 封装错了，团队会把场景经验散落在 prompt、代码和文档各处

6.4 Skill 不是 MCP 原语，也不等于“一段 prompt” ​

很多人第一次做 skill，会犯两个很常见的错误：

  1. 把 skill 写成一段系统提示词
  2. 把 MCP 的 prompts 直接等同于 skill

这两种理解都不够完整。

更稳的工程定义通常是：

skill = instructions + context template + allowed tools + execution policy + output contract

拆开看会更清楚：

  • instructions 说明这个 skill 什么时候该用、目标是什么
  • context template 说明启动时应注入哪些上下文、约束和参考材料
  • allowed tools 决定这个 skill 能看到多大的工具面
  • execution policy 决定是否允许写操作、是否需要 approval、是否能并行
  • output contract 决定返回摘要、产物对象和日志字段长什么样

如果只剩一段 prompt，通常还不够称为 skill；如果只暴露了一组 tools，也还没有形成 skill。

从协议视角看，MCP 里的 prompts 更像 server 暴露给客户端复用的提示模板或交互入口，而不是完整的业务技能包。这里的 skill 更接近一种工程抽象，很多平台也会把类似概念叫做：

  • playbook
  • capability pack
  • task template
  • workflow preset

换句话说，skill 不是行业里唯一统一命名的正式标准，但它非常适合拿来承接“场景经验复用”这一层。

6.5 一个最容易落地的对应关系 ​

如果你还是容易混，最简单的记法可以是：

  • Tool 是“刀”
  • MCP 是“刀柄接口和插座标准”
  • Skill 是“什么时候用哪把刀、按什么顺序做、出了事怎么收口”

拿一个“生产事故分诊”场景举例会更直观：

层级在事故分诊场景里是什么
Toolsearch_runbook、read_recent_alerts、create_incident_ticket
MCP把告警系统、知识库、工单系统按标准协议暴露成 tools/resources/prompts
Skill“事故分诊 Skill”，内部规定先查告警、再读 runbook、最后决定是否升级和建单

这三层的 owner 往往也不同：

  • tool 往往由业务系统或平台工程同学维护
  • MCP server 往往由接入层或基础设施同学维护
  • skill 往往由最懂场景的应用团队、流程 owner 或 AI 产品团队维护

如果 owner 不分，最后就很容易变成：

  • 工具定义写在业务代码里
  • 场景规则写在 prompt 里
  • 权限策略写在前端开关里

这样系统短期能跑，长期一定难维护。

6.6 项目和面试里最好这样讲，而不是一句“我们做了 MCP” ​

最容易失分的说法通常是：

  • “我们接了 MCP，也做了几个 skill，还挂了很多 tool。”

因为这句话没有告诉别人：

  • 你到底标准化了什么
  • 你到底封装了什么
  • 你到底治理了什么

更好的讲法通常是：

  1. 先说 tool：我们把哪些动作做成了稳定可调用的最小能力单元。
  2. 再说 MCP：我们怎么把这些能力按统一协议暴露给 Agent，并处理认证、审批和最小暴露范围。
  3. 最后说 skill：我们怎么把场景经验封成可复用入口，让不同任务只看到自己该看的工具和约束。

例如你可以这样讲：

  • 我们先把 Jira、知识库检索、告警查询拆成独立 tool。
  • 然后通过 MCP 暴露成统一接入层，顺手把 OAuth、审批和 allowed tools 一并收进协议边界。
  • 最后按“事故分诊”“变更巡检”“交付物生成”封成不同 skill，每个 skill 只拿到完成本任务所需的最小工具面。

这样别人一听就能分出来：

  • 你不是只会接工具
  • 你也不是只会写 prompt
  • 你是在做能力分层、暴露治理和场景封装

这才是成熟 Agent 工程最有价值的部分。

7. Tool Use 的执行边界一定要画清楚 ​

根据 Anthropic Tool use 官方文档在 2026-07-07 可访问的说明，Claude 的工具也分成 client tools 和 server tools：

  • client tools 由你的应用执行
  • server tools 由 Anthropic 基础设施执行

这和 OpenAI 体系里的 built-in tools、function tools、MCP/connectors 很像，核心都在强调一件事：

  • 模型只负责提出动作请求，不该被误解成“模型自己在执行外部系统动作”

这个边界如果不画清楚，团队很容易在下面几件事上犯错：

  • 误把模型能力当成权限能力
  • 误把平台可调用当成业务已授权
  • 误把工具失败当成模型推理失败

所以做架构图时，最好明确画出：

  • model decision layer
  • tool execution layer
  • approval / policy layer
  • audit / observability layer

8. MCP 为什么值得重点学 ​

根据 MCP 官方介绍在 2026-07-01 的可访问内容：

  • MCP 是一个开放标准，用于把 AI 应用连接到外部系统
  • 一个常见比喻是“AI 的 USB-C 接口”

这对学习 Agent 很重要，因为它提供了一个统一思维模型：

  • 不同能力都能按统一协议暴露给 Agent

这会让你的系统：

  • 更标准化
  • 更可复用
  • 更容易连接多种数据源与工具

9. MCP 的核心组成 ​

从学习视角，你至少应该理解：

  • server
  • tools
  • resources
  • prompts

tools ​

代表可执行能力。

例如：

  • 搜索
  • 计算
  • 查询数据库

resources ​

代表可读取内容。

例如：

  • 文件
  • 文档
  • 表结构
  • 配置

prompts ​

代表预定义的提示或交互入口。

9.1 resources 和 tools 不要混成一个能力类型 ​

MCP 官方介绍和架构文档反复强调的一点是：

  • tools 是“可执行能力”
  • resources 是“可读取上下文”
  • prompts 是“预定义交互入口”

这不是文档分类游戏，而是系统边界。

如果把 resources 也当成 tools 去用，常见问题是：

  • 为了读一段资料也要走执行链路
  • 审批、审计和超时策略全部混乱
  • 原本只读的内容被误建模成有副作用的动作

更稳的建模方式通常是：

  • 读表结构、读配置、读文档：优先 resources
  • 真正会产生动作、副作用或远端调用：才建成 tools

9.2 remote MCP 的授权流程本身就是设计重点 ​

MCP 官方授权文档和连接远端 server 的文档已经把这件事说得很清楚：

  • 很多 remote MCP server 需要认证
  • 常见方式包括 OAuth、API key 或账号密码
  • MCP 官方安全材料明确推荐用 OAuth 2.1 保护敏感资源和操作

这意味着 remote MCP 接入时，不该只问“协议通不通”，还要问：

  • token 是谁发的
  • token 能访问哪些租户 / 资源
  • 过期和撤销怎么处理
  • 一个 server 被多个 agent / 宿主复用时，凭据边界怎么隔离

如果这层没设计清楚，后面最容易出的问题不是模型选错工具，而是：

  • 本来不该看的租户数据被看到了
  • 一次授权拿到了过宽能力
  • tool result 里混进了别的工作区或别的用户上下文

10. 什么时候该用 MCP，而不是自己手写一堆工具 ​

满足这些条件时，MCP 的价值会更明显：

  1. 工具种类很多
  2. 未来会接入多个宿主或多个 Agent 系统
  3. 希望能力标准化复用
  4. 有企业内部服务要统一暴露
  5. 想把“数据读取”和“能力执行”抽象成统一接口

如果只是一个非常小的单体项目，直接本地工具定义通常也完全没问题。

11. 从 OpenAI 文档看 MCP 的现实意义 ​

根据 OpenAI MCP and Connectors 指南在 2026-07-01 可访问的说明：

  • OpenAI 平台已经把 MCP 工具接入作为一类正式能力来支持
  • 文档里也强调了如何过滤可用工具，以及如何处理工具审批

这说明：

  • MCP 已经不只是“社区概念”
  • 它正在成为 Agent 接外部世界的重要标准层

12. 工具面太大时，要主动收缩暴露范围 ​

根据 OpenAI MCP and Connectors 文档在 2026-07-07 可访问的说明，很多 MCP server 会暴露几十个工具；如果全部暴露给模型，成本、延迟和误调用概率都会上升。官方文档明确给出了 allowed_tools 这种收缩手段，并且允许通过 require_approval 控制审批。

这背后的工程原则其实很朴素：

  • 不是“能连上多少工具”就暴露多少工具
  • 而是“当前任务真正需要什么”才暴露什么

建议至少做三层约束：

  1. 产品层约束：这个页面或场景是否真的需要某类工具。
  2. 运行时约束：本次会话只加载必要工具。
  3. 单工具约束：对高风险能力再做审批和参数白名单。

这会直接改善三件事：

  • 模型更容易选对工具
  • token 成本和回合数更可控
  • 风险面不会因为“方便”而无限膨胀

12.1 工具选择策略最好显式建模，而不是完全放任模型自由发挥 ​

OpenAI 当前 Using tools、Function calling 文档都在强调：

  • tool calling 是一个多步协议
  • 模型会基于你暴露的工具面做选择

工程上更稳的做法通常不是“永远让模型自由决定”，而是给出明确策略：

  • 这一步必须先查事实，再决定是否调用写工具
  • 这一步禁止调用外部写工具
  • 这一步最多允许调用某几类只读工具
  • 这一步如果没有足够证据，就不允许继续执行

换句话说，真正成熟的系统通常会同时控制：

  • tool surface
  • tool choice
  • max iterations
  • approval boundary

12.2 工具收缩最好跟页面、任务、租户和风险级别一起做 ​

很多系统只按“当前会话”收工具，其实还不够。

更像生产系统的收缩方式通常至少有四个维度：

  • 页面 / 入口维度：这个产品入口本来就不该看到某些高危工具
  • 任务维度：本次任务只开放需要的能力
  • 租户维度：不同租户能看到的企业工具面不同
  • 风险维度：高风险动作即使可见，也不能无审批直通

如果没有这几层，常见结果就是：

  • 某个低风险页面意外拿到了高风险工具面
  • 工具太多导致模型误选
  • 同一个 agent 在不同租户下权限表现不一致，却没人解释得清楚

12.3 最好显式维护一层 capability registry，而不是把工具清单散在代码里 ​

很多团队前期工具不多时，会直接把工具定义散在各个模块里。

但工具一旦变多，真正先失控的往往不是模型，而是：

  • 谁知道有哪些工具
  • 哪些工具属于哪个业务域
  • 哪些工具已经废弃
  • 哪些工具需要审批或更高权限

更像生产系统的做法通常会维护一层 capability registry，至少能回答：

  • tool_id
  • owner
  • risk_level
  • allowed_tenants
  • required_auth_scope
  • approval_policy
  • artifact_output_type
  • version
  • deprecation_state

这层 registry 的价值非常大，因为它会直接决定：

  • tool search 能搜到什么
  • Router / manager 能调起什么
  • 评测系统要覆盖哪些高风险工具
  • 发布和回滚时到底影响了哪一组能力

13. approval 不是锦上添花，而是高风险工具的必需层 ​

很多团队会在 Demo 跑通后才想审批，但一旦工具能：

  • 发消息
  • 改权限
  • 写数据库
  • 删资源
  • 操作生产环境

审批就不应该再被当成可选项。

根据 OpenAI MCP and Connectors 文档在 2026-07-07 可访问的说明，远端 MCP 与 connector 工具可以配置 require_approval，并支持审批请求与审批响应的回合式交互。这说明审批不只是产品层弹窗，它本身就是工具协议的一部分。

落到系统设计里，至少要保留这些对象：

字段作用
approval_request_id审批动作的稳定标识
tool_name当前待放行的具体工具
tool_arguments_snapshot审批时看到的参数快照
risk_level高、中、低风险分级
approved_by谁做的决策
decision_reason放行、拒绝或修改原因

否则事后很难回答：

  • 这次写操作到底是谁批的
  • 审批时和最终执行时参数是否一致

13.1 审批之后最好把执行参数再绑定一次 ​

真正危险的场景通常不是“有没有审批”，而是：

  • 审批通过的是一组参数
  • 最终执行时跑的是另一组参数

所以更稳的做法通常会多存几类字段：

  • approved_arguments_hash
  • approved_scope
  • expires_at
  • execution_idempotency_key

这样你才能回答：

  • 这次执行是不是仍然在批准范围内
  • 审批是否已经过期
  • 失败重试时会不会重复制造副作用

13.2 授权范围最好和工具面同时收缩，而不是只靠“是否登录” ​

很多系统会默认：

  • 只要用户登录了
  • agent 就可以代表用户调一批工具

这远远不够。

更稳的做法通常至少要同时问三件事：

  1. 用户本人 是否有这个权限
  2. 当前 agent / workflow 是否被允许代执行
  3. 当前场景 是否满足最小必要范围

也就是说，授权判断最好至少包含：

  • user scope
  • agent scope
  • task scope

如果没有这三层，常见风险会是：

  • 用户本来能看数据，但 agent 不该自动导出
  • 用户本来有改单权限，但某个 FAQ 场景根本不该暴露写工具
  • 同一个租户下的低风险助手意外继承了高风险工具面

14. 远端 MCP 最大的风险，不是“调不通”，而是信任边界错了 ​

OpenAI 官方文档对 remote MCP 有一句非常值得认真对待的提醒：

  • 开发者必须信任自己接入的 remote MCP server，因为恶意 server 可能从进入模型上下文的内容里窃取敏感信息

这句话的工程含义很重。它说明远端 MCP 的首要问题不是协议兼容，而是：

  • 这个 server 到底是谁维护的
  • 它能看到什么
  • 它会把什么再回传给模型

因此接入远端 MCP 时，建议把下面这些问题当成上线前检查项：

  1. server 是否可信、是否可审计。
  2. 是否会接触密钥、PII、生产数据。
  3. 工具返回结果里是否可能带 prompt injection 或诱导内容。
  4. 是否为不同租户做了隔离。
  5. 是否能做最小权限 OAuth 授权。

如果这些问题答不清，协议再标准，接入也依然不安全。

14.1 tool result 也要当不可信输入处理 ​

不管是 remote MCP、第三方 connector，还是内部工具，返回结果都不该被默认当成“绝对可信的自然语言上下文”。

因为现实里它可能包含：

  • 诱导模型执行下一步的文本
  • 混入的 prompt injection
  • 超长无关日志
  • 租户错位的信息

更稳的处理方式通常是：

  1. 先做结构化校验。
  2. 再做字段级截断、清洗和白名单提取。
  3. 只把当前决策真正需要的字段回送给模型。
  4. 原始结果保存在审计或调试层，不直接整包注入上下文。

否则系统很容易进入一种危险状态：

  • 工具调用本来是为了提高确定性
  • 结果却通过未净化返回把新的不确定性重新注入模型

14.2 remote MCP 和 connectors 最容易漏掉的是令牌与租户边界 ​

远端接入一旦走 OAuth、API key 或 SaaS connector，真正危险的通常不是“技术接通”，而是：

  • 谁在代表谁访问
  • 访问结果是不是跨了租户
  • token 续期和撤销后旧会话还会不会继续用

更稳的设计通常至少要有这些字段或概念：

  • connection_id
  • tenant_id
  • authorized_scopes
  • connected_account_id
  • expires_at
  • revoked_at
  • consent_source

这样后面你才能真正回答：

  • 这个结果到底来自哪个外部身份
  • 为什么这个租户能看到这份数据
  • 某次授权撤销后，历史 session 是否还应继续使用旧连接

15. 企业内部工具接入的一个推荐顺序 ​

建议按以下顺序做：

  1. 先做只读工具
  2. 再做低风险写入工具
  3. 最后才做高风险执行工具

并且始终分层：

  1. 数据读取层
  2. 业务逻辑层
  3. Agent 调用层

这样你未来更容易：

  • 做权限控制
  • 做审批
  • 做审计
  • 替换底层系统

15.1 shell / computer use / browser automation 更像独立执行层，不只是多一个工具 ​

OpenAI 当前 Shell、Local shell、Computer use 文档都在反复强调一件事：

  • 这类能力不是简单的“查一个 API”
  • 它们会进入终端、文件系统、UI 环境或持续执行循环

这意味着当你接入：

  • shell
  • local shell
  • code interpreter
  • computer use

时，真正要设计的不只是 schema，而是：

  • 工作区生命周期
  • 端口 / 文件暴露范围
  • 可恢复执行记录
  • 输出产物保存
  • 失败后的清理和补偿

如果把它们只当“普通工具”，后面几乎一定会在恢复、权限和审计上出问题。

15.2 异步工具和长作业最好按“提交 - 轮询 - 回收产物”三段式建模 ​

很多企业工具不会立刻返回最终结果，例如：

  • 导出报表
  • 跑批量分析
  • 触发长时脚本
  • 发起代码扫描或部署检查

如果把这类动作强行当成同步 tool call，常见后果就是：

  • 超时
  • 重试语义混乱
  • 模型不知道结果什么时候可用

更稳的契约通常会拆成三段：

  1. submit_job
  2. get_job_status
  3. fetch_job_artifact

这样好处很直接：

  • 模型和工作流能分清“已提交”和“已完成”
  • 审批、回放和恢复更容易定位到哪一段
  • 产物可以单独进入 artifact 层，而不是直接塞回工具返回文本

16. handoff、tools-as-agents 和 MCP server，什么时候该选哪一个 ​

很多团队一旦开始拆 Agent，就会把三件事混在一起：

  • handoff
  • 把另一个 agent 当工具
  • 直接接 MCP server

更实用的判断方式通常是：

16.1 handoff 适合什么 ​

更适合：

  • 用户意图已经明显切换
  • 需要换一个 specialist 持续接管后续回合
  • 新 agent 需要自己的上下文、策略和边界

OpenAI 当前 Orchestration and handoffs 的主线就是把 handoff 当作“控制权迁移”。

16.2 tools-as-agents 适合什么 ​

更适合：

  • 当前 agent 只是临时调用一个受控子能力
  • 子能力需要独立推理，但不需要长期接管对话
  • 你希望保留统一的上层控制和停止条件

这更像：

  • agent 调 agent，但外层仍然把它当一个受控工具

16.3 MCP server 适合什么 ​

更适合：

  • 你已经有一批稳定的企业能力需要标准化暴露
  • 不同宿主、不同 agent 系统都可能复用这层能力
  • 你想把工具、资源、提示入口统一成协议层

如果只是一个很小的单体应用，把本地工具写清楚往往更直接。

16.4 一个简单判断法 ​

可以先问自己四个问题：

  1. 这是能力调用，还是控制权迁移。
  2. 这是单次子任务，还是后续多轮都要由另一个 specialist 接管。
  3. 这是本项目私有接口，还是未来要被多宿主复用的标准能力。
  4. 这一步失败后，谁负责回退、补偿和对外解释。

17. 工具契约除了 schema，还要覆盖错误语义 ​

很多工具文档只写输入参数和返回字段，但在真实 Agent 系统里，错误语义同样重要。

如果工具只会返回一个模糊的 error，模型和工作流层就很难判断：

  • 这是参数错误
  • 还是权限不足
  • 还是远端暂时超时
  • 还是副作用已经成功，只是回包丢了

更可执行的返回契约，至少应该考虑这些维度：

字段作用
retryable是否建议自动重试
side_effect_confirmed外部副作用是否已确认落地
recommended_next_action建议续跑、重试、补偿还是转人工
error_scope参数层、权限层、外部系统层或业务层
external_reference远端对象或请求 ID

这样工作流恢复、人工接管和评测系统才有机会做对分流。

17.1 幂等性和执行记录最好进入工具契约 ​

很多外部动作真正难的不是“能不能调”，而是：

  • 超时之后到底有没有成功
  • 重试时会不会重复发消息、重复扣款、重复建单

所以高风险工具最好显式补一层执行记录，例如：

字段作用
execution_id单次执行的稳定标识
idempotency_key防止重复副作用
attempt第几次尝试
side_effect_state未执行、已执行、未知、需确认
compensation_hint失败后建议补偿路径

这样恢复系统和人工接管台才能分清：

  • 是可以直接自动重试
  • 还是必须先确认外部世界到底发生了什么

17.2 tool output 最好先标准化，再回送模型 ​

除了错误语义，正常结果也最好先做标准化。

更稳的路径通常是：

  • 工具返回原始结构
  • 应用层做 normalize / redact / summarize
  • 模型消费的是稳定的二次结构

这会直接改善：

  • 跨工具的一致性
  • 回归测试稳定性
  • 多模型切换时的兼容性

17.3 工具返回的“产物对象”最好和“模型可见摘要”分开 ​

很多工具真正重要的结果并不是一小段文本，而是：

  • 一个导出的文件
  • 一个生成的表格
  • 一个网页快照
  • 一个工单对象
  • 一个 deployment / run record

这类结果更适合拆成两层：

  1. artifact
  2. model-facing summary

也就是：

  • 系统保存完整产物对象及其 ID
  • 模型只消费下一步决策真正需要的摘要、状态和引用

更像生产系统的 artifact 字段通常至少包括：

  • artifact_id
  • artifact_type
  • source_tool
  • created_at
  • visibility_scope
  • retention_policy
  • trace_id

这样后面你才更容易做：

  • 回放
  • 审计
  • 人工接管
  • 产物清理与保留策略

18. 工具接入后的观测和评测不能缺席 ​

工具接得越多，系统越容易出现一种错觉：

  • 问题看起来像模型不够聪明
  • 其实是工具设计、权限控制或执行质量出了问题

所以建议至少单独监控这些指标：

  • tool_selection_accuracy
  • tool_argument_error_rate
  • tool_timeout_rate
  • approval_rate
  • approval_reject_rate
  • duplicate_side_effect_rate
  • per_tool_latency

如果有 Agent 评测体系，还应该把这些维度纳入回归：

  • 是否选对工具
  • 是否用对参数
  • 是否在不需要工具时过度调用
  • 是否把高风险动作正确升级到审批

18.1 工具接入最好单独补 contract test，而不是只靠端到端用例 ​

很多团队接一个工具后，只有：

  • “让 agent 跑一下看看”

这对真实系统远远不够。

更稳的做法通常至少会补三层验证：

  1. schema / contract test
  2. permission / approval test
  3. end-to-end trace test

这三层各自解决不同问题：

  • contract test 看参数和返回结构有没有漂移
  • permission test 看不该暴露的工具会不会漏出来
  • end-to-end trace test 看 loop、审批和恢复是否真的串起来

如果只做最后一层，你很容易把工具契约问题误判成模型问题。

否则工具层的问题会被混在“模型效果不好”里，团队很难真正优化。

19. 工具接入时最常见的 8 个坑 ​

  1. 工具定义太宽泛
  2. 参数过多过杂
  3. 错误信息不可读
  4. 读写没有分离
  5. 没有审批和日志
  6. 把 remote MCP / connector 返回结果原样整包喂回模型
  7. shell / computer use 接进来后，没有把工作区当独立执行层治理
  8. 只有 schema，没有 idempotency、execution record 和补偿语义

只要踩中其中两个，Agent 的稳定性通常就会明显下降。

20. 重点官方资源 ​

以下资源已按 2026-07-09 复核到当前正式入口；其中部分 OpenAI 页面对脚本访问会返回 403，但浏览器入口仍可正常打开：

21. 本章后的练习建议 ​

建议你至少做 6 个练习：

  1. 设计一个搜索工具 schema
  2. 设计一个企业工单查询工具 schema
  3. 设计一组“读写分离”的客户信息工具
  4. 为一个 remote MCP server 设计最小暴露工具面和 OAuth 授权边界
  5. 为一个带副作用的写工具设计 approval + idempotency + execution record 契约
  6. 以“事故分诊”为题，分别写出 tool 清单、MCP 暴露边界和 skill 契约，强迫自己把三层彻底拆开

完成标准不是“能调用”，而是你能回答：

  • 这个工具为什么这样设计？
  • 哪些参数是必须的？
  • 哪些风险被隔离掉了？